【笔记】对接接口定义标准化规范

发表于 | 分类于

[笔记系列文章说明]: 该类型的文章是笔者学习过程中整理的学习笔记.

与不绝对信任的机构或企业交换数据的时候, 通常需要考虑严格的数据安全问题, 我在这里定义了一种, 完整版就不放了, 列一些关键的点

文档定义

一, 接口访问定义

请求方式: http请求post方式
请求类型: application/json;charset=utf-8
返回类型: application/json;charset=utf-8
域名:

二, 参数定义

  1. 请求头信息(Header)
参数 类型 说明 例
plantformCode String 商家授权码 如:
timeStamp Long 时间戳 如:1626255054672 (相当于2021-07-14 17:30:54)
sign String 签名 8d2472fac5a4a1879bde18075f7a879e
  1. 请求体内容(Body),具体内容依据具体接口
参数 类型 说明 例
messageId String 消息唯一标识
data String JSON字符串
timeStamp Long 时间戳
dataSource String 数据来源,供应商唯一标识 如BOLIAN 
1
2
3
4
5
{
"messageId":”9527”,
"data":"[{\"id\":54,\"gpsId\":\"Auth\",\"longitude\":18.98,\"latitude\":43.44,\"direction\":180,\"speed\":555,\"timeStamp\":1626321005219}]",
"timeStamp":1626321005219
}
  1. 签名生成方式: MD5,32位,小写
  • 第一步: 获取data内容
    例如:
    1
    String data = "{\"id\":54,\"gpsId\":\"Auth\",\"longitude\":18.98,\"latitude\":43.44,\"direction\":180,\"speed\":555,\"timeStamp\":1626321005219}";
  • 第二步: append秘钥 (对接时由企橙提供唯一秘钥salt)
    1
    StringBuffer str = new StringBuffer(data).append(salt);
  • 第三步: 进行MD5加密
    1
    sign=MD5(str)
  1. 返回结果格式
参数 类型 说明 例
code Integer 状态码 200:成功
message String 消息内容
result Json 接口返回内容
timeStamp Long 时间戳 
1
2
3
4
5
6
7
8
9
10
{
"code":stc200,
"message":stc"成功",
"result":stc{
"id":stc"9527",
"dataSource":stcnull,
"gpsId":stc"Auth"
},
"timeStamp":stc1626332760670
}

三, 接口内容

  1. 车辆GPS数据上报接口
    描述: 接收供应商上传的GPS数据
    地址: http://域名/openApi/gps/push
    参数
参数名称 参数类型 是否必传 描述
id String 是 记录唯一标识
gpsId String 是 Gps唯一标识(设备号)
longitude Double 是 经度
latitude Double 是 纬度
direction Integer 是 方向
speed Integer 是 速度
timeStamp Long 是 时间戳
参数例子 
1
2
3
4
5
{
"messageId":"9527",
"data": "[{\"id\":9527,\"gpsId\":\"Auth\",\"longitude\":18.98,\"latitude\":43.44,\"direction\":180,\"speed\":555,\"timeStamp\":1626321005219}]",
"timeStamp":1626320711603 
}

返回

返回名称 返回类型 是否必返 描述
code Integer 是 返回码,200:成功
message String 是 返回消息
result Json 否 返回内容
timeStamp Long 是 时间戳
返回例子 
1
2
3
4
5
6
{
"code": 200,
"message": "成功",
"result": null,
"timestamp": 1626332760670
}